老子写个代码而已，凭什么还要我写文档？
这两天我的朋友圈被程序员和产品经理的打架视频刷了屏，说是因为产品经理要求根据手机壳颜色更换 APP 主题的颜色，然后程序员忍无可忍就干起来了。边看我还边在想，这不太可能。应该是段子手又在编段子了，不过从这个转发量来看，可以间接地发现，程序员和产品经理在沟通和信任中还是有许多问题存在的。
https://v.qq.com/txp/iframe/player.html?vid=g0745abluu2&width=500&height=375&auto=0
话说打架的这两位主人公都被炒鱿鱼了，不过他们又特么打起来了：
https://v.qq.com/txp/iframe/player.html?vid=s0743q3947h&width=500&height=375&auto=0
虽然这是一个段子，但是从中我们可以思考一下，产品经理的思维和技术人员的思维是存在偏差的，互不理解，如果再加上沟通问题，那么积累久了要么是离职走人，要么就是像上面这样的事情发生。
所以我一直认为，咱们搞技术的不要一个劲的使用技术思维去思考问题，不要局限自己，人生不设限，做个斜杆青年，一专多能，比较好些。
1.什么是docString
说了点废话，咱们接下来进入 Python 正题， 今天给大家说说写文档这点事情。
很多程序员其实不太喜欢写文档的，因为觉得文档这事儿好像不关自己的事情，代码才是。老子写个代码而已，凭什么还要我写文档？
Python 有个叫做 docString 的东西完美解决了这问题，让你直接在代码中写文档，其实说白了就是给代码写点注释，什么语言都会有给代码写注释的，不过 Python 的 docString 可以直接把你的注释变成文档，是不是很厉害？
2.怎么使用docString
在函数、方法、模块、类中的第一句注释语句就是 docString，可以通过 help（） 或者 __doc__ 进行访问。
比如这里的 requests 模块的 docString 是这样的：
-*- coding: utf-8 -*-
__
/__) _ _ _ _ _/ _
/ ( (- (/ (/ (- _) / _)
/
"""
Requests HTTP Library
~~~~~~~~~~~~~~~~~~~~~
Requests is an HTTP library, written in Python, for human beings. Basic GET
usage:
>> import requests
>> r = requests.get('https://www.python.org')
>> r.status_code
200
>> 'Python is a programming language' in r.content
True
... or POST:
>> payload = dict(key1='value1', key2='value2')
>> r = requests.post('http://httpbin.org/post', data=payload)
>> print(r.text)
{
...
"form": {
"key2": "value2",
"key1": "value1"
},
...
}
The other HTTP methods are supported - see `requests.api`. Full documentation
is at <http://python-requests.org>.
:copyright: (c) 2017 by Kenneth Reitz.
:license: Apache 2.0, see LICENSE for more details.
"""我们可以通过 help(requests) 或者 requests.__doc__ 就可以访问到它的文档了。
接下来我们自己写一个docString吧。
我们定义一个叫 myDoc 的函数，传入两个参数，再写一下docString，告诉别人我们的函数是干嘛的，传入的参数是什么，返回什么。
"""
this is myDoc function
:param param1: this is a first param
:param param2: this is a second param
:return: param1 + param2
"""
print(param1 + param2)
return param1 + param2
是不是一目了然。
而且我们还可以使用 sphinx 的 autodoc 自动从docString生产api文档。是不是很方便呢？
相关文章：
关注我，让你像看小黄文一样轻松学到 Python 的所有！
ps：还没获取我精心准备的 Python 电子书和思维导图等干货的可以在我的公众号「学习Python的正确姿势」中发送 python 免费获取哦！
再ps:说真的，如果你能点个赞转发支持我一下我会更有动力写。
顺手